home *** CD-ROM | disk | FTP | other *** search
/ SGI Hot Mix 17 / Hot Mix 17.iso / HM17_SGI / research / examples / misc / wexmast / wtips.txt < prev    next >
Text File  |  1997-07-08  |  7KB  |  140 lines
  1. IDL/widgets Programming Tips and Techniques
  2.  
  3.  
  4. Widgets and Widget Applications
  5.  
  6. In this document, an individual graphical user interface element (e.g., a
  7. slider, button, menu, et cetera) is called a "widget". A group of widgets
  8. that work together to perform a task is called a "widget application". 
  9.  
  10.  
  11.  
  12. Basic Configuration of Widget Applications
  13.  
  14. A widget application contains at least two procedures. One procedure creates
  15. the widgets and another serves as an event handler for the created widgets.
  16. Both procedures are usually contained within the same text file with the
  17. event handler procedure listed first and the widget creation procedure listed
  18. last. Look at the files used in the "Simple Widgets" for examples.
  19.  
  20. Note that you can write and run the "widget creation" procedure part of a
  21. widget application before writing the "event handler" part. In this way, you
  22. can prototype your user interfaces before actually "hooking up" the buttons,
  23. sliders, and other widgets to perform real actions.
  24.  
  25.  
  26.  
  27. Use a Template when Creating New Widget Applications
  28.  
  29. A good place to start your widget applications is with the procedure
  30. XMNG_TMPL.PRO.  This file is a template for writing widget applications. At
  31. the top of this file is a documentation header. An event handler procedure
  32. and widget creation procedure follow. Note that a "Done" button and "Tools"
  33. menu are already "hooked up". By using this template as a starting place,
  34. your widget applications will be easier to create and will be written in a
  35. style consistent with the widget applications that RSI provides with IDL.
  36. Make a copy of XMNG_TMPL.PRO with the appropriate new file name and add your
  37. own functionality to it using the "Simple Widget Examples" as a guide.
  38.  
  39.  
  40.  
  41. WIDGET ID's, "event.id", VALUES, and USER VALUES
  42.  
  43. Every widget created has a unique "widget ID" associated with it. This ID is
  44. held in the variable that was used in the initial widget creation call. For
  45. example, the widget ID of the following slider:
  46.  
  47.      coolslider = WIDGET_SLIDER(base, TITLE = 'Cool Slider')
  48.  
  49. is held in the variable "coolslider".
  50.  
  51. Many widgets also have VALUES. The meanings of widget VALUES and their
  52. variable types are different for different types of widgets. The VALUE of a
  53. button widget is the button label.  The VALUE of a draw widget is its IDL
  54. window number. The VALUE of a label widget is the label's text. The VALUE of
  55. a list widget is the array of list elements. The VALUE of a text widget is
  56. the string contents of the text widget. The initial value of a widget is set
  57. using the VALUE keyword to the widget creation function. The VALUE of a
  58. widget can be examined by using the GET_VALUE keyword to the WIDGET_CONTROL
  59. routine. The VALUE of a widget can be changed by using the SET_VALUE keyword
  60. to the WIDGET_CONTROL procedure.
  61.  
  62. Every widget can also have a user-specified value associated with it. This
  63. value is called a USER VALUE. A USER VALUE is simply a "parasite" that is
  64. associated with a widget but performs no function by itself. The initial USER
  65. VALUE is specified using the UVALUE keyword to the widget creation function,
  66. and the USER VALUE can be of any type. The USER VALUE of a widget can be
  67. examined by using the GET_UVALUE keyword to the WIDGET_CONTROL procedure.
  68. USER VALUES can be changed by using the SET_UVALUE keyword to the
  69. WIDGET_CONTROL procedure.
  70.  
  71. When a widget is manipulated by a user, an event structure is returned. This
  72. event structure is an IDL structure that has different fields depending upon
  73. the type of widget that has been manipulated. One of the fields that is
  74. always returned, no matter what type of widget is manipulated, is the "id"
  75. field. This field contains the widget ID of the most recently manipulated
  76. widget. The event.id field can be used to find out which widget was
  77. manipulated and act accordingly. For example, to find the USER VALUE of the
  78. most recently manipulated widget, use the command:
  79.  
  80.      WIDGET_CONTROL, event.id, GET_UVALUE = eventval
  81.  
  82. The variable "eventval" will hold the USER VALUE of the most recently
  83. manipulated widget.  If you want to act based on widget VALUES instead, use
  84. the command:
  85.  
  86.      WIDGET_CONTROL, event.id, GET_VALUE = eventval
  87.  
  88. The variable "eventval" will hold the VALUE of the most recently manipulated
  89. widget. Note that the GET_UVALUE and GET_VALUE keywords perform a sort of
  90. reverse assignment operation -- the VALUE or USER VALUE is put into
  91. "eventval", not vice versa.
  92. Of course, both techniques could be used simultaneously with the command:
  93.  
  94.      WIDGET_CONTROL, event.id, GET_VALUE = eventval, GET_UVALUE = eventuval
  95.  
  96. Now you would know both the VALUE and the USER VALUE of the most recently
  97. manipulated widget.
  98.  
  99. Once the USER VALUE and/or VALUE of a widget is known, it is easy to use a
  100. CASE statement to perform different actions based upon either the VALUE or
  101. USER VALUE. Almost all of the Simple Widget Examples use a CASE statement
  102. that performs different functions based upon USER VALUES.
  103.  
  104. Another field that is always returned in the event structure is "event.top",
  105. the widget ID of the top-level base. This field is most often used for
  106. supplying a widget ID to the "WIDGET_CONTROL, event.top, /DESTROY" command. 
  107.  
  108.  
  109.  
  110. COMMON Blocks
  111.  
  112. Sometimes it is necessary for both a widget creation routine and its
  113. associated event handler routine to explicitly know about a variable,
  114. especially a widget's "widget ID". To let both procedures know the necessary
  115. variables or widget ID's, use a COMMON block.
  116. For example, if the label on a button whose widget ID is held in the variable
  117. "changebutton" needs to change after some arbitrary event, both the creation
  118. and event handler procedures would need a common block similar to this one:
  119.  
  120. COMMON widgetblock, changebutton
  121.  
  122. A call to WIDGET_CONTROL in the event handler procedure could then be used to
  123. change the button's label with the command line:
  124.  
  125.      WIDGET_CONTROL, changebutton, SET_VALUE = 'New Value'
  126.  
  127. Unfortunately, when a COMMON block is used in this manner, only one copy of
  128. the widget application should be allowed to run at a time. If multiple copies
  129. are allowed, the multiple copies of the application will share the same
  130. COMMON block and errors and general confusion may result. To ensure that only
  131. one copy of a widget application is allowed at a time, put the line:
  132.  
  133.      IF (XREGISTERED("name") NE 0) THEN RETURN
  134.  
  135. where "name" is the name of the procedure, near the top of the widget
  136. creation procedure part of your widget application.
  137. For other examples of using COMMON blocks with widget ID's, see the code for
  138. the "Label/Text Widget" and the "Slot Machine Demo".
  139.  
  140.